Summary

GSD tools fail on Windows in three distinct ways: (1) npm test and npm run test:coverage silently find zero test files because PowerShell/cmd do not expand shell globs like tests/*.test.cjs, (2) path.join() produces backslash-separated paths (.planning\phases\01-setup) in JSON output that downstream consumers (Claude Code agents, CLAUDE.md file-read instructions) cannot resolve on Windows, and (3) test assertions that pass JSON strings containing $ or ["a","b"] through execSync shell interpolation get corrupted on Windows (and can fail on any platform depending on shell state).

Root Cause

1. Shell glob expansion in npm scripts (CI failure)

package.json used a bare shell glob:

"test": "node --test tests/*.test.cjs"

On Linux/macOS, bash expands tests/*.test.cjs before invoking node. On Windows, PowerShell and cmd pass the literal string tests/*.test.cjs to Node, which does not recognize it as a glob — resulting in zero test files found and a silent pass.

2. path.join() producing backslash paths in output (runtime bug)

Multiple functions in core.cjs and init.cjs used path.join() to construct paths returned in JSON output:

// core.cjs — searchPhaseInDir
directory: path.join(relBase, match),

// init.cjs — cmdInitTodos
path: path.join('.planning', 'todos', 'pending', file),

// init.cjs — cmdInitPlanPhase, cmdInitPhaseOp
result.context_path = path.join(phaseInfo.directory, contextFile);

On Windows, path.join('.planning', 'phases', '01-setup') returns .planning\phases\01-setup. Consumers that read these paths (Claude Code agents, downstream commands) expect forward slashes and fail to locate files.

3. Shell interpolation of $ and JSON in test commands (test reliability)

Tests passed arguments containing dollar signs and JSON through execSync with shell interpolation:

runGsdTools("state add-decision --summary 'Benchmark prices moved from $0.50 to $2.00'", tmpDir);
runGsdTools(`frontmatter set ${file} --field tags --value '["a","b"]'`);

Shells interpret $0, $2 as positional parameters (expanding to empty strings or the shell name). On Windows, single quotes are not special — the JSON brackets and quotes get mangled. Both cases silently corrupt the argument before it reaches the CLI.

Fix

Commit 1 (ea0e712): Add shell: bash to both test steps in .github/workflows/test.yml. This ensures GitHub Actions uses bash on Windows runners, providing reliable glob expansion as a quick mitigation.

Commit 2 (edaa673): Create scripts/run-tests.cjs — a cross-platform test runner that resolves test files via fs.readdirSync() instead of shell globs. Update package.json to use node scripts/run-tests.cjs for both test and test:coverage scripts. This eliminates the dependency on shell glob expansion entirely.

Commit 3 (4c91f74): Propagate NODE_V8_COVERAGE environment variable in the test runner by spreading process.env into the child process. Without this, c8 cannot collect coverage data from the subprocess.

Commit 4 (13a8b0e): Three sub-fixes in one commit:

• Path separators: Add toPosixPath() helper to core.cjs that normalizes path.sep to /. Apply it to all 10 path-construction sites in core.cjs (searchPhaseInDir, findPhaseInternal) and init.cjs (cmdInitPlanPhase, cmdInitPhaseOp, cmdInitTodos, cmdInitProgress). For paths that are purely string literals with no OS-dependent segments, use direct string concatenation ('.planning/phases/' + dir) instead of path.join().

• JSON quoting: Convert 3 test calls in frontmatter-cli.test.cjs and 2 in state.test.cjs from string-based runGsdTools() to array-based form, bypassing shell interpolation entirely.

• Test helper: Extend runGsdTools() in tests/helpers.cjs to accept string[] in addition to string. When an array is passed, it uses execFileSync (no shell) instead of execSync (shell), preventing all shell-interpolation issues.

Commit 5 (c58d9fe): Update the cmdInitTodos test assertion from path.join('.planning', 'todos', 'pending', 'task-1.md') to the literal '.planning/todos/pending/task-1.md', matching the new forward-slash output.

Edge cases handled:

• toPosixPath() is a no-op on Linux/macOS (separator is already /)
• The runGsdTools() string overload is preserved for backward compatibility with existing tests that don't need shell-safe arguments
• env: { ...process.env } in the test runner copies the full environment including NODE_V8_COVERAGE, PATH, and any user-set variables

Relationship to Other PRs

This is PR 3 of 6 from the dev-bugfix branch, split for independent review:

No code overlap between PRs. Each can be merged independently in any order. This PR touches files (core.cjs, init.cjs, helpers.cjs, run-tests.cjs, test.yml, package.json) that no other PR modifies.

Testing

Tests directly exercising the fixes

Full suite results

Node.js test runner (v22, Linux)
────────────────────────────────
Test files:    7 (commands, config, frontmatter-cli, init, phases, state, verify)
Test suites:  79
Tests:       419 passed, 0 failed, 0 skipped
Duration:     10.6s

Coverage (c8):
─────────────────────────────────────────────────────
File             │ Stmts  │ Branch │ Funcs  │ Lines
─────────────────────────────────────────────────────
All files        │ 90.36% │ 81.50% │ 98.03% │ 90.36%
core.cjs         │ 90.95% │ 92.09% │  100%  │ 90.95%
init.cjs         │ 98.59% │ 80.57% │  100%  │ 98.59%
frontmatter.cjs  │ 92.64% │ 82.20% │  100%  │ 92.64%
state.cjs        │ 96.90% │ 82.98% │  100%  │ 96.90%
─────────────────────────────────────────────────────
Coverage threshold: 70% lines ✅

Impact

9 files changed, 84 insertions(+), 29 deletions(-)